Inside Macintosh: QuickDraw GX Objects /

Chapter 7 - View-Related Objects / View-Related Objects Reference

View Device Functions / Manipulating View Device Object Properties

GXSetViewDeviceClip

You can use the GXSetViewDeviceClip function to set the clip property of a view device object.

void GXSetViewDeviceClip(gxViewDevice target, gxShape clip);

target

A reference to the view device whose clip you wish to set.

clip

A reference to a shape object whose geometry describes the clip to be assigned.

DESCRIPTION

The GXSetViewDeviceClip function copies information from the shape
object referenced by the clip parameter into the clip property of the view device object referenced by the target parameter. You can specify nil for the clip parameter, in which case this function sets the clip property of the target view device to a full clip. (A full clip indicates that QuickDraw GX is not to apply view device clipping to shapes that reference this view device.)

Although a filled rectangle is the most common clip shape for a view device, the new clip shape may be a geometric shape, a bitmap shape, or a glyph shape. It may not be a picture, text, or layout shape.

• If you specify a geometric shape, it must be in primitive form--that is, all the stylistic information about the shape must be incorporated into the shape's geometry--because this function copies only the geometry-related information from the shape you specify. It does not copy the information contained in the shape's style. You can convert a shape to its primitive form using the GXPrimitiveShape function, which is described in Inside Macintosh: QuickDraw GX Graphics. You can also specify an empty or full shape for a clip.
• If you specify a bitmap shape, it must have a pixel size of 1 and its color profile reference must be nil. In the bitmap, pixel values of 0 obscure drawing; pixel values of 1 do not restrict visibility. The GXSetViewDeviceClip function copies the pixel image from the bitmap to the clip property of the target view device.
• If you specify a glyph shape, this function uses information from the glyph shape's style object as well as its style list to determine the size, form, and position of the glyph outlines; those outlines are then used to clip drawing. The style list cannot have nil entries. A style object referenced by the glyph shape cannot be complex--that is, it cannot have a cap, join, dash, pattern, text face, font variation, tag list, or any of the properties used only by layout shapes.

You only need to call this function if you want to restrict the part of the device that displays your view ports--for example, to clip out the area reserved for live video in your offscreen copy of an onscreen view device.

Because it is copied into the view device object, changing the clip shape after calling GXSetViewDeviceClip does not affect the view device's clip.

SPECIAL CONSIDERATIONS

You cannot change the clip of a view device in the onscreen view group.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
invalid_viewDevice_reference
colorProfile_must_be_nil	(debugging version)
bitmap_pixel_size_must_be_1	(debugging version)
empty_shape_not_allowed	(debugging version)
ignorePlatformShape_not_allowed	(debugging version)
nil_style_in_glyph_not_allowed	(debugging version)
complex_glyph_style_not_allowed	(debugging version)
illegal_type_for_shape	(debugging version)
shapeFill_not_allowed	(debugging version)
viewDevice_access_restricted	(debugging version)
Notices (debugging version)
clip_already_set
tags_in_shape_ignored

SEE ALSO

For information about geometric shapes and bitmap shapes, see Inside Macintosh: QuickDraw GX Graphics. For information about glyph shapes, see Inside
Macintosh: QuickDraw GX Typography.

To retrieve a copy of the clip property, use the GXGetViewDeviceClip function, described in the previous section.